GetRequirementsForImage() only checks an exact scope key and then falls back to the transport default/global default. The containers-policy.json format supports hierarchical scope matching (most-specific scope should win, e.g. docker.io/library applying to docker.io/library/nginx). With the current exact-match logic, common real-world policies will be ignored unless the caller provides an exact key. Consider implementing longest-prefix (most-specific) match for scopes before falling back to "" and the global default.

TestGetDefaultPolicyPath branches based on whether the user’s real $HOME/.config/containers/policy.json currently exists, so its expectations depend on the machine/environment running the tests. This makes the test suite flaky and potentially environment-dependent. Prefer setting HOME to a temp dir and explicitly creating/removing the policy file to cover each branch deterministically.

TestPolicy_Save_ErrorCases relies on POSIX directory permissions (0555) to make the directory read-only. This can behave differently on Windows, and can also fail to produce an error when running with elevated privileges (e.g. root in CI), making the test non-portable/flaky. Consider skipping on platforms/users where permissions aren’t enforced, or use a deterministic failure case (e.g. invalid path / injecting a write failure).

Adding an exported field to the public remote.Repository struct is a source-compatible breaking change for downstream users who construct Repository with positional composite literals (without field names). If preserving that compatibility matters, consider making policy configuration available via an option (e.g. RepositoryOptions) or an unexported field with setter methods, rather than adding a new exported struct field.

Policy enforcement is only applied in Fetch, Push, and Resolve, but other public entry points that perform registry operations (e.g. FetchReference, PushReference, Tag, Delete, Exists, Mount, Tags, etc.) still bypass checkPolicy(). This makes policy enforcement inconsistent and easy to accidentally circumvent from within the same API surface. Consider enforcing policy at a lower level (e.g. in the underlying blob/manifest stores or request creation) or ensuring all relevant repository operations call checkPolicy() with an appropriate fully-qualified reference.

checkPolicy() builds imageRef.Scope as r.Reference.Repository (e.g. library/nginx) and, for Resolve, may set imageRef.Reference to the raw tag/digest string (e.g. "latest"). containers-policy.json docker scopes/refs are typically matched against fully-qualified names (e.g. docker.io/library/nginx and docker.io/library/nginx:latest), so this will cause scope-specific policies to never match and can break signed-identity matching. Build scope as <registry>/<repository> and always pass a fully-qualified reference (e.g. by constructing a registry.Reference{Registry:..., Repository:..., Reference:...}.String() or reusing r.ParseReference).

The comment says “No requirements means reject by default for safety”, but the code returns a non-nil error when len(reqs) == 0. Either adjust the comment to match the behavior, or change the behavior to return (false, nil) if an empty requirement set is meant to be a clean deny decision.

TestLoadDefault writes a real policy.json into the current user’s home directory ($HOME/.config/containers/policy.json) and removes it afterward. This makes the test suite stateful and can clobber a developer’s existing config (or behave differently depending on what already exists). Prefer isolating the home dir by setting HOME/USERPROFILE to t.TempDir() (via t.Setenv) and constructing paths under that temp home.

SetDefault assigns reqs (type []PolicyRequirement) directly to p.Default (type PolicyRequirements), and SetTransportScope assigns reqs directly into the TransportScopes map. These are distinct named slice types in Go, so this code will not compile. Convert the variadic slice to PolicyRequirements (and consider copying) before assigning.

This is the most critical issue in this PR. The spec states that for the docker: transport, "More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest), a repository namespace, or a registry host". The current implementation only does exact string match.

For example, a policy with scope docker.io/library should match image docker.io/library/nginx:latest, but this code would fall through to the transport default instead. Wildcard subdomain matching (*.example.com) is also required by the spec.

Should we implement proper prefix-based scope matching with longest-prefix-wins semantics? This is fundamental to the correctness of the policy evaluation.

The spec says: "Exactly one of keyPath, keyPaths and keyData must be present." This validation only checks that at least one is present. It should reject configurations where multiple key sources are specified simultaneously.

The signedBy spec does not define a keyDatas field nor a SignedByKeyData struct. The spec fields are: keyPath (string), keyPaths (array of strings), keyData (string, base64-encoded). Should we remove KeyDatas to match the spec?

PRSigstoreSigned is missing several fields defined in the spec:

• keyPaths (array of key file paths)
• pki (non-Fulcio X.509 certificate config with caRootsPath, caRootsData, caIntermediatesPath, caIntermediatesData, subjectHostname, subjectEmail)
• rekorPublicKeyPaths (array of Rekor public key paths)
• rekorPublicKeyDatas (array of base64-encoded Rekor public key data)

Also, the spec says keyDatas is ["base64-encoded-public-key-one-data", ...] — a simple string array, not []SigstoreKeyData. The current SigstoreKeyData struct with PublicKeyFile/PublicKeyData fields does not correspond to anything in the spec.

If we intentionally don't support some fields yet, we should document this and the JSON parser should reject policies containing unsupported fields rather than silently ignoring them.

Per the spec: "If fulcio is present... Both oidcIssuer and subjectEmail are mandatory." The FulcioConfig.Validate() only checks for CA path/data. We need to validate OIDCIssuer and SubjectEmail as well.

nit: marshalWithType does marshal → unmarshal-to-map → add type → marshal-again. This triple serialization is fragile — []byte fields will be double-base64-encoded if the intermediate map representation doesn't preserve the raw bytes correctly. Consider using a wrapper struct with an embedded type field instead.

The scope is set to r.Reference.Repository, but per the spec, docker scopes are the fully expanded form — e.g., docker.io/library/busybox:latest (not busybox:latest). Does r.Reference.Repository always produce the fully expanded form? If a user creates a Repository with reference library/nginx, will the scope be docker.io/library/nginx or just library/nginx? This matters for correct policy matching.

Policy is checked for Fetch, Push, and Resolve, but not for Delete, Tag, or Manifests().PushReference(). Is this intentional? The spec-based policy.json is typically applied to pull/push operations, but we should document which operations are covered and which are not.

nit: fmt.Errorf("policy cannot be nil") — should this be a sentinel error? In oras-go convention, consider returning an existing errdef error or at least using %w for wrappable errors.

nit: Go convention — exported constants that are implementation details of the package path resolution should be unexported unless SDK users need them. Do SDK users need PolicyConfUserDir, PolicyConfFileName, and PolicyConfSystemPath?